HAL RTC functions

RTC exported write protection and initialization mode functions.

group RTC_Exported_Functions_Write_Init

Write protection and initialization mode.

RTC write protection.

The RTC peripheral has its own write protection. After backup domain reset, some of the RTC registers are protected against parasitic write access.

Calling HAL_RTC_DisableWriteProtection and HAL_RTC_EnableWriteProtection disables and enables the write protection respectively.

Initialization mode

The initialization mode of the RTC permits to initialize and configure the RTC calendar. Entering this mode stops the calendar counter.

Calling HAL_RTC_EnterInitMode and HAL_RTC_ExitInitMode makes the RTC enter and exit initialization mode, respectively.

Functions

hal_status_t HAL_RTC_EnableWriteProtection ( void )

Enable the RTC registers write protection.

Note

Not all RTC registers are concerned by the write protection.

Return values :

HAL_OK –

hal_status_t HAL_RTC_DisableWriteProtection ( void )

Disable the RTC registers write protection.

Note

Not all RTC registers are concerned by the write protection.

Return values :

HAL_OK –

hal_status_t HAL_RTC_EnterInitMode ( void )

Enter the RTC initialization mode.

Warning

The RTC initialization mode is write protected. Use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

  • HAL_OK –

  • HAL_ERROR – RTC does not enter initialization mode before the RTC timeout duration.

hal_status_t HAL_RTC_ExitInitMode ( void )

Exit the RTC initialization mode.

Warning

The RTC initialization mode is write protected. Use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

  • HAL_OK –

  • HAL_ERROR – Calendar resynchronization is still pending after timeout duration.

RTC exported configuration functions

group RTC_Exported_Functions_Config

Configuration functions for prescaler values and RTC mode.

RTC clock and prescalers

The RTC clock, named RTCCLK, is configured by the RCC driver using HAL_RCC_RTC_SetKernelClkSource. The RTCCLK source can be LSE, LSI, or HSE. The RTC peripheral has a programmable prescaler stage that can be configured to generate a 1 Hz clock. To minimize consumption, the prescaler is split into two programmable prescalers:

  • A 7-bit asynchronous prescaler (PREDIV_A).

  • A 15-bit synchronous prescaler (PREDIV_S).

When using both prescalers, it is recommended to configure the asynchronous prescaler to a high value to minimize consumption. By default, the asynchronous and synchronous prescalers are set to 128 and 256 to obtain a clock frequency of 1 Hz with an RTCCLK configured to an LSE of 32.768 kHz.

The following equation gives the clock frequency after the first prescaler: freq_async_clk = freq_rtcclk/(1+ hal_rtc_config_t::asynch_prediv)

The following equation gives the clock frequency after the two prescalers: freq_sync_clk = freq_rtcclk/((1+ hal_rtc_config_t::asynch_prediv)(1+ hal_rtc_config_t::synch_prediv))

The values of the prescalers can be changed by calling HAL_RTC_SetConfig and setting the value of hal_rtc_config_t::asynch_prediv and hal_rtc_config_t::synch_prediv. To change the values of the prescalers, the RTC needs to be in initialization mode by calling HAL_RTC_EnterInitMode.

RTC running modes.

RTC supports three operating modes:

  • BCD mode for Binary-Coded Decimal

  • Binary mode

  • Mixed mode

The mode is chosen by selecting the value of hal_rtc_config_t::mode and calling HAL_RTC_SetConfig.

Binary-Coded Decimal mode

The BCD mode is a feature that allows the RTC to store and display time and date information in a BCD format. BCD is a way of representing decimal numbers using four bits per digit, with each digit ranging from 0 to 9. In BCD mode, the subseconds down-counter is clocked by the signal after the first prescaler. When the down-counter reaches 0, it is reloaded with the value of the synchronous prescaler. Only the first 16 bits of the subsecond register are used in BCD mode.

Binary mode

In binary mode, the subseconds down-counter is clocked by the signal after the first prescaler. The subsecond register is extended to 32-bit length and is free running. The value of the synchronous register is not used, and the time and date registers are not used. In this mode, users can use all functions that include the keyword Binary in their names that are optimized for it.

Mixed mode

This mode, as stated by its name, is a mix between the two previous modes. The subseconds down-counter is extended to 32-bit length and is free running. The time and date calendar in BCD are also functional. The down-counter is still clocked by the signal after the asynchronous prescaler, but the seconds of the calendar are incremented each time the least significant bits of the subsecond register reach 0. The number of bits taken into account are defined by configuring HAL_RTC_SetConfig and changing the value of hal_rtc_config_t::bcd_update.

To change the RTC mode, the RTC needs to be in initialization mode by calling HAL_RTC_EnterInitMode.

Functions

hal_status_t HAL_RTC_SetConfig ( const hal_rtc_config_t * p_config )

Program the RTC prescaler values and the RTC mode according to the specified parameters.

Warning

The RTC configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC configuration must be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_config – pointer to an RTC configuration instance.

Return values :

  • HAL_OK. –

  • HAL_INVALID_PARAM – p_config is NULL.

void HAL_RTC_GetConfig ( hal_rtc_config_t * p_config )

Retrieve the RTC prescaler values and the RTC mode.

Parameters :

p_config – pointer to an RTC configuration instance.

RTC exported low power configuration functions

group RTC_Exported_Functions_Low_Power

Low power configuration functions.

It is possible to drastically reduce the RTC power consumption by setting the RTC to low power mode. In this configuration the whole RTC is clocked by the ck_apre.

When the division factor of the asynchronous prescaler is not a power of 2 (( hal_rtc_config_t::asynch_prediv +1) % 2 == 0), the low power mode cannot be activated.

Functions

hal_status_t HAL_RTC_EnableUltraLowPowerMode ( void )

Enable the RTC ultra low power mode.

Note

When ( hal_rtc_config_t::asynch_prediv + 1) is not a power of 2, calling this function does not enable low power mode.

Warning

The RTC low power configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_DisableUltraLowPowerMode ( void )

Disable the RTC ultra low power mode.

Warning

The RTC configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_rtc_ultra_low_power_mode_status_t HAL_RTC_IsEnabledUltraLowPowerMode ( void )

Check whether the RTC ultra low power mode is enabled.

Return values :

hal_rtc_ultra_low_power_mode_status_t – Ultra low power mode status.

RTC exported calendar functions

group RTC_Exported_Functions_Calendar

Exported calendar functions.

The RTC calendar stores and displays time and date information in a BCD format. It includes subseconds, seconds, minutes, hours, weekday, date, month, and year. The calendar works only in BCD or mixed mode; otherwise, only the subseconds down-counter register works.

Calendar configuration

Calendar hour format and shadow registers.

Set the hour format to 24-hour or 12-hour format by programming hal_rtc_calendar_config_t::hour_format and calling HAL_RTC_CALENDAR_SetConfig.

Shadow registers

The shadow registers mirror the values of the calendar date and time registers. When the shadow registers are not bypassed, the application reads the values of date and time in the shadow registers. Reading the time locks the values in calendar shadow registers to ensure consistency between time and date values; reading the date unlocks them. Call HAL_RTC_CALENDAR_GetTime before HAL_RTC_CALENDAR_GetDate, or call HAL_RTC_CALENDAR_GetDateTime to retrieve the time and date correctly. The application can access the date and time registers directly by bypassing the shadow registers. Use hal_rtc_calendar_config_t::bypass_shadow_register to configure the shadow register bypass.

Other calendar services

Reference clock detection

In BCD mode only, the update of the RTC calendar can be synchronized to a reference clock. This reference clock is used to compensate for the imprecision of the calendar seconds update frequency. This detection is only enabled if the prescalers are set to their default values, which are 128 and 256 for hal_rtc_config_t::asynch_prediv and hal_rtc_config_t::synch_prediv respectively.

Binary mode

A dedicated API is provided to optimize the code when using binary mode. The function HAL_RTC_CALENDAR_GetBinaryTime retrieves the value of the subseconds down-counter register.

Summer time and hour increment and decrement

The functions HAL_RTC_CALENDAR_EnableSummerTimeMemorization and HAL_RTC_CALENDAR_DisableSummerTimeMemorization allow an application to keep information about the summer time status. These functions do not alter the hour registers. Increment or decrement the hours by using HAL_RTC_CALENDAR_AddOneHour and HAL_RTC_CALENDAR_SubtractOneHour respectively, which are independent of the summer time memorization bit.

Subseconds underflow

In binary or mixed mode, enable the subsecond underflow interrupt. This interrupt triggers when the subseconds down-counter underflows.

Functions

hal_status_t HAL_RTC_CALENDAR_SetConfig ( const hal_rtc_calendar_config_t * p_config_calendar )

Program the bypass shadow registers and calendar hour format according to the specified parameters.

Warning

The RTC calendar configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC calendar configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_config_calendar – pointer to an RTC calendar configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config_calendar is NULL.

void HAL_RTC_CALENDAR_GetConfig ( hal_rtc_calendar_config_t * p_config_calendar )

Retrieve the bypass shadow registers and calendar hour format configuration.

Parameters :

p_config_calendar – pointer to an RTC calendar configuration instance.

hal_status_t HAL_RTC_CALENDAR_SetTime ( const hal_rtc_time_t * p_time )

Program the RTC time.

Note

hal_rtc_time_t::microsec field is ignored because it is not used in the SetTime function.

Note

hal_rtc_time_t::millisec field is ignored because it is not used in the SetTime function.

Note

hal_rtc_time_t::subsec field is ignored because it is not used in the SetTime function.

Warning

The RTC time configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC time configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_time is NULL.

hal_status_t HAL_RTC_CALENDAR_GetTime ( hal_rtc_time_t * p_time )

Retrieve the RTC time.

Note

When using the shadow registers (default): Reading RTC current time locks the values in calendar shadow registers to ensure consistency between time and date values. Call HAL_RTC_CALENDAR_GetDate to unlock the time value.

Parameters :

p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – When a timeout occurs on the shadow register flag

hal_status_t HAL_RTC_CALENDAR_SetDate ( const hal_rtc_date_t * p_date )

Program the RTC date.

Warning

The RTC date configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC date configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

p_date – pointer to an RTC date instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date is NULL.

hal_status_t HAL_RTC_CALENDAR_GetDate ( hal_rtc_date_t * p_date )

Retrieve the RTC date.

Parameters :

p_date – pointer to an RTC date instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – When a timeout occurs on the shadow register flag

hal_status_t HAL_RTC_CALENDAR_SetDateTime ( const hal_rtc_date_t * p_date , const hal_rtc_time_t * p_time )

Program the RTC date and time.

Note

hal_rtc_time_t::microsec field is ignored because it is not used in the SetDateTime function.

Note

hal_rtc_time_t::millisec field is ignored because it is not used in the SetDateTime function.

Note

hal_rtc_time_t::subsec field is ignored because it is not used in the SetDateTime function.

Warning

The RTC date and time configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC date and time configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Parameters :

  • p_date – pointer to an RTC date instance.

  • p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date or p_time are NULL.

hal_status_t HAL_RTC_CALENDAR_GetDateTime ( hal_rtc_date_t * p_date , hal_rtc_time_t * p_time )

Retrieve the RTC date and time.

Parameters :

  • p_date – pointer to an RTC date instance.

  • p_time – pointer to an RTC time instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – When a timeout occurs on the shadow register flag

hal_status_t HAL_RTC_CALENDAR_EnableReferenceClock ( void )

Enable the reference clock detection.

Note

The detection only works when RTC is set to BCD mode only HAL_RTC_MODE_BCD, the synchronous prescaler hal_rtc_config_t::synch_prediv and the asynchronous prescaler hal_rtc_config_t::asynch_prediv are set to 0x00FF (default value) and to 0x007F (default-value) respectively.

Warning

The RTC reference clock configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC reference clock configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_DisableReferenceClock ( void )

Disable the reference clock detection.

Warning

The RTC reference clock configuration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

The RTC reference clock configuration needs to be called when RTC is in initialization mode, use HAL_RTC_EnterInitMode to enter initialization mode.

Return values :

HAL_OK –

hal_rtc_calendar_reference_clock_status_t HAL_RTC_CALENDAR_IsEnabledReferenceClock ( void )

Check if the reference clock detection is enabled or disabled.

Return values :

hal_rtc_calendar_reference_clock_status_t – Reference clock detection status

hal_status_t HAL_RTC_CALENDAR_AddOneHour ( void )

Add one hour to the calendar in a single operation without going through the initialization procedure.

Warning

The RTC hour increment is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_SubtractOneHour ( void )

Subtract one hour from the calendar in a single operation without through the initialization procedure.

Warning

The RTC hour decrement is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_EnableSummerTimeMemorization ( void )

Enable the summer time memorization bit status.

Warning

The RTC summer time memorization bit is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_DisableSummerTimeMemorization ( void )

Disable the summer time memorization bit status.

Warning

The RTC summer time memorization bit is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

HAL_OK –

hal_rtc_calendar_summer_time_status_t HAL_RTC_CALENDAR_IsEnabledSummerTimeMemorization ( void )

Check if the summer time memorization bit is enabled or disabled.

Return values :

hal_rtc_calendar_summer_time_status_t – Summer time memorization bit status.

uint32_t HAL_RTC_CALENDAR_GetBinaryTime ( void )

Retrieve the subsecond register value.

Return values :

uint32_t – Value of the subsecond register.

hal_status_t HAL_RTC_CALENDAR_EnableITSubSecondsUnderflow ( void )

Enable the subsecond register underflow interruption.

Return values :

HAL_OK –

hal_status_t HAL_RTC_CALENDAR_DisableITSubSecondsUnderflow ( void )

Disable the subsecond register underflow interruption.

Return values :

HAL_OK –

hal_rtc_calendar_it_underflow_status_t HAL_RTC_CALENDAR_IsEnabledITSubSecondsUnderflow ( void )

Check if the subsecond register underflow interruption is enabled or disabled.

Return values :

hal_rtc_calendar_it_underflow_status_t – Subsecond register underflow interruption status

hal_rtc_calendar_status_t HAL_RTC_CALENDAR_IsInitialized ( void )

Check if the calendar is initialized.

Return values :

hal_rtc_calendar_status_t – Calendar initialization status.

RTC exported output functions

group RTC_Exported_Functions_Output

Exported output functions.

To enable the output signals, call HAL_RTC_OUTPUT_Enable. To use RTC_OUT1 as input, all outputs must be disabled on RTC_OUT1. Disable all outputs by calling HAL_RTC_OUTPUT_Disable, or configure the outputs on RTC_OUT2 by calling HAL_RTC_OUTPUT_Enable with hal_rtc_output_t values that contain only OUT2 in their names.

Configuration of the TAMPALRM output signal

The TAMPALRM output is the OR between rtc_tamp_evt and ALARM output.

ALARM output can be selected between alarm A, alarm B, or wake-up outputs.

Depending on the application needs, configure the polarity, the output type, and the use of a pull-up by using HAL_RTC_OUTPUT_SetConfigTampalarm. When configuring the output to open-drain, set the GPIO as input by using HAL_GPIO_Init from the GPIO driver.

Configuration of the calibration output signal

The calibration output signal corresponds to the RTCCLK clock signal after the 6th stage of the asynchronous prescaler or the 8th stage of the synchronous prescaler (and all the asynchronous prescaler).

To choose between these two configurations, call HAL_RTC_OUTPUT_SetConfigCalib.

Asynchronous clock calibration

The calibration clock is the output of the 6th stage of the asynchronous prescaler. Thus, only the first 6 bits are used to define the calibration frequency. The frequency of the output is (freq_RTCCLK / (PREDIV_A[5:0]+1)), PREDIV_A given by hal_rtc_config_t::asynch_prediv.

If low power mode is disabled and the value of the asynchronous prescaler is strictly below 0x20, the calibration signal output does not work.

With the prescaler at default values and using LSE, the clock frequency is 512 Hz.

Synchronous clock calibration

The calibration output is the output of the 8th stage of the synchronous prescaler. Thus, only the first 8 bits are used to define the calibration frequency. The frequency of the output is (freq_RTCCLK/((PREDIV_A+1) * (PREDIV_S[7:0] +1)). PREDIV_S and PREDIV_A given by hal_rtc_config_t::synch_prediv and hal_rtc_config_t::asynch_prediv respectively.

With the prescaler at default values and using LSE, the clock frequency is 1 Hz.

Functions

hal_status_t HAL_RTC_OUTPUT_SetConfigTampalarm ( const hal_rtc_output_tampalarm_config_t * p_config )

Program the tampalarm configuration.

Warning

When configuring tampalarm in open-drain mode HAL_RTC_OUTPUT_TAMPALARM_TYPE_OPENDRAIN The RTC_OUT1 GPIO must be set to input in GPIO driver.

Parameters :

p_config – pointer to the tampalarm configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config is NULL.

void HAL_RTC_OUTPUT_GetConfigTampalarm ( hal_rtc_output_tampalarm_config_t * p_config )

Retrieve the tampalarm configuration.

Parameters :

p_config – pointer to the tampalarm configuration instance.

hal_status_t HAL_RTC_OUTPUT_SetConfigCalib ( const hal_rtc_output_calib_config_t * p_config )

Program the calibration output configuration.

Note

When using the synchronous calibration (1Hz by default), the calibration output is the output of the 8th stage of the synchronous prescaler. Thus only the 8 first bits are used to define the calibration frequency The frequency of the output is (f_RTCCLK/((PREDIV_A+1) * (PREDIV_S[7:0] +1)).

Note

When using the asynchronous calibration (512Hz by default), the calibration output is the output of the asynchronous prescaler 6th stage. Thus only the 6 first bits are used to define the calibration frequency. The frequency of the output is (f_RTCCLK / (PREDIV_A[5:0]+1)).

Warning

If low power mode is disabled and the value of the asynchronous prescaler hal_rtc_config_t::asynch_prediv is strictly below 0x20, the calibration signal output does not work.

Parameters :

p_config – pointer to the calibration output configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config is NULL.

void HAL_RTC_OUTPUT_GetConfigCalib ( hal_rtc_output_calib_config_t * p_config )

Retrieve the calibration output configuration.

Parameters :

p_config – pointer to the calibration output configuration instance.

hal_status_t HAL_RTC_OUTPUT_Enable ( hal_rtc_output_t output )

Enable the output of the calibration signal or/and tampalarm signal.

Parameters :

output – Value of hal_rtc_output_t.

Return values :

HAL_OK –

hal_status_t HAL_RTC_OUTPUT_Disable ( void )

Disable the output RTC output.

Return values :

HAL_OK –

hal_rtc_output_status_t HAL_RTC_OUTPUT_IsEnabled ( hal_rtc_output_t output )

Check if the RTC output is enabled or disabled.

Parameters :

output – Value of hal_rtc_output_t representing the output configuration to be checked.

Return values :

hal_rtc_output_status_t:HAL_RTC_OUTPUT_DISABLED – RTC output status.

RTC exported calibration functions

group RTC_Exported_Functions_Calibration

Exported calibration functions.

Smooth digital calibration

The RTC frequency can be calibrated with a very small resolution of about 0.954 ppm with a range from -487.1 ppm to 488.5 ppm. This adjustment is made on the RTCCLK or the clock after the asynchronous prescaler when low power mode is enabled.

To activate the smooth calibration, one needs to call HAL_RTC_EnableCalibration with the parameters pulse_add or subtracted_pulses set to HAL_RTC_CALIBRATION_PULSE_INSERTED or a value different from 0 respectively. The subtracted_pulses specifies the number of pulses of the clock to be masked during the calibration cycle chosen by the calibration_period. If calibration_period is set to HAL_RTC_CALIBRATION_PERIOD_16SEC or HAL_RTC_CALIBRATION_PERIOD_8SEC the first bit and the two first bit are stuck at 0 respectively.

Setting the pulse_add parameter inserts one extra pulse every 2^11 cycles which doesn’t dependent on the calibration period.

The frequency after calibration is given by this formula freq_calib = freq_RTCCLK x [1 + ( pulse_add x 512 - subtracted_pulses) / (2^20 + subtracted_pulses - pulse_add x 512)]

When the value of the asynchronous prescaler hal_rtc_config_t::asynch_prediv is inferior to 3 no pulses are inserted, thus making the parameter pulse_add is ignored.

To stop the calibration call HAL_RTC_DisableCalibration. To retrieve the status of the calibration call HAL_RTC_IsEnabledCalibration.

Synchronization of RTC the calendar

After reading the subsecond register and calculating an offset with the remote clock, the goal of this feature is to synchronize the RTC by adding/subtracting the offset to synchronize the RTC with the remote clock. The shift operation consists of adding or subtracting some subseconds depending on the parameters of the HAL_RTC_ShiftCalibration. The param add_one_sec adds one second to the time register and the param fraction_sec_to_subtract subtract some subseconds to the subsecond register.

The shift operation does not work properly in the following cases:

  1. In BCD mode :HAL_RTC_MODE_BCD, if the reference clock is enabled.

  2. In BCD mode :HAL_RTC_MODE_BCD, the 15th value of the subsecond register is equal to 1.

  3. In mixed mode :HAL_RTC_MODE_MIX, the fraction_sec_to_subtract [14, hal_rtc_config_t::bcd_update ] must be equal to 0.

  4. In mixed mode :HAL_RTC_MODE_MIX, the BCD increment value hal_rtc_config_t::bcd_update in the subsecond register must be equal to 0.

Functions

hal_status_t HAL_RTC_EnableCalibration ( hal_rtc_calibration_period_t calibration_period , hal_rtc_calibration_pulse_t pulse_add , uint32_t subtracted_pulses )

Enable the smooth calibration parameters.

Note

To activate the smooth calibration, the parameters pulse_add or subtracted_pulses must be set to HAL_RTC_CALIBRATION_PULSE_INSERTED or a value different from 0, respectively. If calibration_period is set to HAL_RTC_CALIBRATION_PERIOD_16SEC or HAL_RTC_CALIBRATION_PERIOD_8SEC the first bit and the first two bits are stuck at 0, respectively. If PREDIV_A ( hal_rtc_config_t::asynch_prediv) is less than 3, the bit CALP set by pulse_add is always equal to 0, thus pulse_add is ignored. The frequency after calibration is given by this formula: F_CAL = F_RTCCLK x [1 + ( pulse_add x 512 - subtracted_pulses) / (2^20 + subtracted_pulses - pulse_add x 512)]

Warning

The RTC calibration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

When low power mode is enabled (use HAL_RTC_EnableUltraLowPowerMode), the calibration mechanism is applied to the RTCCLK after the asynchronous prescaler.

Parameters :

  • calibration_period – Select the smooth calibration period, values from hal_rtc_calibration_period_t.

  • pulse_add – Choose between increasing the frequency by one pulse every 2^11 pulses or no pulse insertion (hal_rtc_calibration_pulse_t).

  • subtracted_pulses – Number of pulses to subtract out of 2^20 pulses.

Return values :

  • HAL_OK –

  • HAL_ERROR – If a recalibration operation is still ongoing after RTC timeout duration.

hal_status_t HAL_RTC_DisableCalibration ( void )

Disable the smooth calibration parameters.

Warning

The RTC calibration is write protected, use the HAL_RTC_DisableWriteProtection before calling this function.

Return values :

  • HAL_OK –

  • HAL_ERROR – If a recalibration operation is still ongoing after RTC timeout duration.

hal_rtc_calibration_status_t HAL_RTC_IsEnabledCalibration ( void )

Check if the smooth calibration is enabled.

Return values :

hal_rtc_calibration_status_t – RTC smooth calibration status.

hal_status_t HAL_RTC_ShiftCalibration ( hal_rtc_calibration_shift_second_t add_one_sec , uint32_t fraction_sec_to_subtract )

Shift the RTC clock (Subsecond Register) by a fraction of a second.

Note

the RTC calibration is write protected. Use the HAL_RTC_DisableWriteProtection before calling this function.

Warning

This feature is not compatible with the reference clock detection feature enabled by HAL_RTC_CALENDAR_EnableReferenceClock

Warning

This function will not decrease the number of seconds nor overflow the subsecond register.

Parameters :

  • add_one_sec – Choose between adding one second to the clock.

  • fraction_sec_to_subtract – Number of fraction of a second to subtract.

Return values :

  • HAL_OK –

  • HAL_ERROR – The shift operation is still pending after RTC timeout duration. RTC_SHIFTR must not be written when the reference clock detection is enabled. In BCD mode, SS[15] must be 0 before writing RTC_SHIFTR to avoid overflow. In mixed mode, SUBFS[14:BCDU+8] must be written with 0. In mixed mode, SS[BCDU+8] must be 0 before writing RTC_SHIFTR.

RTC exported alarm functions

group RTC_Exported_Functions_Alarms

Exported alarm functions.

The RTC unit provides two programmable alarms. The alarms trigger when the calendar subseconds, seconds, minutes, hours, day of month, or weekday match the values of the alarm. Each field can be independently masked by setting hal_rtc_alarm_date_time_t::mask. When the alarm triggers, it can be automatically cleared by setting the parameter hal_rtc_alarm_config_t::auto_clear to HAL_ALARM_AUTO_CLEAR_ENABLE.

To update the alarms configuration, RTC must be in initialization mode or the alarms must be disabled by using HAL_RTC_EnterInitMode or HAL_RTC_ALARM_Stop respectively.

Binary mode

When using the binary mode only the subsecond registers are compared. A dedicated API is given to optimize the code. The subseconds down-counter register can be reloaded every time the alarms triggers which means that the subseconds down-counter register is running from 0xFFFF FFFF to the value set in the subseconds registers of the alarm. This can only be used in binary mode. This is configured by setting hal_rtc_alarm_config_t::subsec_auto_reload to HAL_RTC_ALARM_SUBSECONDS_AUTO_RELOAD_ENABLE.

Functions

hal_status_t HAL_RTC_ALARM_SetConfig ( hal_rtc_alarm_t alarm , const hal_rtc_alarm_config_t * p_config_alarm )

Configure the alarm parameters.

Note

hal_rtc_alarm_config_t::subsec_auto_reload can be enabled only in binary mode.

Parameters :

  • alarm – Select the alarm A or B.

  • p_config_alarm – Pointer to the alarm configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config_alarm is NULL.

  • HAL_ERROR – If the alarm is started and the RTC is not in initialization mode. or if p_config_alarm->subsec_auto_reload is set to LL_RTC_ALMA_SUBSECONDBIN_AUTOCLR_YES and RTC is in BCD or Mixed mode.

void HAL_RTC_ALARM_GetConfig ( hal_rtc_alarm_t alarm , hal_rtc_alarm_config_t * p_config_alarm )

Retrieve the alarm configuration.

Parameters :

  • alarm – Select the alarm A or B.

  • p_config_alarm – Pointer to the alarm configuration instance.

hal_status_t HAL_RTC_ALARM_SetDateTime ( hal_rtc_alarm_t alarm , const hal_rtc_alarm_date_time_t * p_date_time )

Configure the alarm date and time.

Warning

The synchronous prescaler value, hal_rtc_config_t::synch_prediv, must be greater than 3 when seconds are unmasked.

Parameters :

  • alarm – Select the alarm A or B.

  • p_date_time – Pointer to the alarm date and time instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date_time is NULL.

  • HAL_ERROR – if the alarm is started and the RTC is not in initialization mode.

void HAL_RTC_ALARM_GetDateTime ( hal_rtc_alarm_t alarm , hal_rtc_alarm_date_time_t * p_date_time )

Retrieve the alarm date and time.

Parameters :

  • alarm – Select the alarm A or B.

  • p_date_time – Pointer to the alarm date and time instance.

hal_status_t HAL_RTC_ALARM_Start ( hal_rtc_alarm_t alarm , uint32_t interruption )

Start the alarm.

Parameters :
Return values :

HAL_OK –

hal_status_t HAL_RTC_ALARM_Stop ( hal_rtc_alarm_t alarm )

Stop the alarm.

Parameters :

alarm – Select the alarm A or B.

Return values :

HAL_OK –

hal_status_t HAL_RTC_ALARM_PollForEvent ( hal_rtc_alarm_t alarm , uint32_t timeout_ms )

Poll for alarm event.

Parameters :

  • alarm – Select the alarm A or B.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK –

  • HAL_TIMEOUT – when reaching the timeout during polling.

hal_status_t HAL_RTC_ALARM_SetBinaryTime ( hal_rtc_alarm_t alarm , uint32_t alarm_subsecond )

Program the alarm subseconds.

Note

Use in binary mode only. Prefer HAL_RTC_ALARM_SetDateTime to program the alarm in BCD or mixed mode.

Parameters :

  • alarm – Select the alarm A or B.

  • alarm_subsecond – Alarm subsecond value. Value between 0x0 and 0xFFFFFFFF.

Return values :

  • HAL_OK –

  • HAL_ERROR –

uint32_t HAL_RTC_ALARM_GetBinaryTime ( hal_rtc_alarm_t alarm )

Retrieve the alarm subseconds.

Note

Use in binary mode only. Prefer HAL_RTC_ALARM_GetDateTime to retrieve alarm subseconds in BCD or mixed mode.

Parameters :

alarm – Select the alarm A or B.

Return values :

uint32_t – Alarm subseconds.

hal_status_t HAL_RTC_ALARM_SetBinarySubSecondMask ( hal_rtc_alarm_t alarm , uint32_t alarm_subsecond_mask )

Program the alarm subseconds mask.

Note

Use in binary mode only. Prefer HAL_RTC_ALARM_SetDateTime to program the alarm in BCD or mixed mode.

Parameters :

  • alarm – Select the alarm A or B.

  • alarm_subsecond_mask – Alarm subsecond mask. Value between 0x0 and 0x3F.

Return values :

HAL_OK –

uint32_t HAL_RTC_ALARM_GetBinarySubSecondMask ( hal_rtc_alarm_t alarm )

Retrieve the alarm subseconds mask.

Note

Use in binary mode only. Prefer HAL_RTC_ALARM_GetDateTime to retrieve alarm subseconds mask in BCD or mixed mode.

Parameters :

alarm – Select the alarm A or B.

Return values :

uint32_t – Alarm subseconds mask.

RTC exported timestamp functions

group RTC_Exported_Functions_Timestamp

Exported timestamp functions.

Timestamp is enabled by setting the TSE bit of RTC_CR register to 1. When TSE is set, the calendar is saved in the timestamp registers (RTC_TSSSR, RTC_TSTR, RTC_TSDR) when a timestamp event is detected on the RTC_TS pin.

When TAMPTS is set: The calendar is saved in the timestamp registers (RTC_TSSSR, RTC_TSTR, RTC_TSDR) when an internal or external tamper event is detected.

After a timestamp event, by calling the HAL_RTC_TIMESTAMP_GetDateTime, the application can retrieve the date and time of the last timestamp event and clear the timestamp registers.

Functions

hal_status_t HAL_RTC_TIMESTAMP_SetConfig ( const hal_rtc_timestamp_config_t * p_config_timestamp )

Configure the RTC timestamp.

Parameters :

p_config_timestamp – pointer to an RTC timestamp configuration instance.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_config_timestamp is NULL.

void HAL_RTC_TIMESTAMP_GetConfig ( hal_rtc_timestamp_config_t * p_config_timestamp )

Retrieve the RTC timestamp configuration.

Parameters :

p_config_timestamp – pointer to an RTC timestamp configuration instance.

hal_status_t HAL_RTC_TIMESTAMP_EnablePinSource ( void )

Enable the RTC timestamp from the external pin (RTC_TS).

Return values :

HAL_OK –

hal_status_t HAL_RTC_TIMESTAMP_DisablePinSource ( void )

Disable the RTC timestamp from the external pin (RTC_TS).

Return values :

HAL_OK –

hal_rtc_timestamp_status_t HAL_RTC_TIMESTAMP_IsEnabledPinSource ( void )

Check if the RTC timestamps from the external pin (RTC_TS) is enabled.

Return values :

hal_rtc_timestamp_status_t – RTC timestamp from the external pin status.

hal_status_t HAL_RTC_TIMESTAMP_EnableTamperSource ( void )

Enable the RTC timestamp on tamper event.

Return values :

HAL_OK –

hal_status_t HAL_RTC_TIMESTAMP_DisableTamperSource ( void )

Disable the RTC timestamp on tamper event.

Return values :

HAL_OK –

hal_rtc_timestamp_tamper_status_t HAL_RTC_TIMESTAMP_IsEnabledTamperSource ( void )

Check whether the RTC timestamp on tamper event is enabled.

Return values :

hal_rtc_timestamp_tamper_status_t – RTC timestamp on tamper event status.

hal_status_t HAL_RTC_TIMESTAMP_EnableIT ( void )

Enable the RTC timestamp interrupt.

Return values :

HAL_OK –

hal_status_t HAL_RTC_TIMESTAMP_DisableIT ( void )

Disable the RTC timestamp interrupt.

Return values :

HAL_OK –

hal_rtc_timestamp_it_status_t HAL_RTC_TIMESTAMP_IsEnabledIT ( void )

Check if the RTC timestamp interrupt is enabled.

Return values :

hal_rtc_timestamp_it_status_t – RTC timestamp interrupt status.

hal_status_t HAL_RTC_TIMESTAMP_GetDateTime ( hal_rtc_time_t * p_time , hal_rtc_date_t * p_date , hal_rtc_timestamp_information_t * p_info )

Retrieve the RTC timestamp time and the source of the timestamp event. Due to register limitations, the year is forced to 0 when reading the timestamp.

Parameters :

  • p_time – pointer to an RTC timestamp time instance.

  • p_date – pointer to an RTC timestamp date instance.

  • p_info – pointer to a hal_rtc_timestamp_information_t value. It is used to retrieve the flag of the timestamp event.

Return values :

  • HAL_OK –

  • HAL_INVALID_PARAM – when p_date or p_time are NULL.

  • HAL_ERROR – When an overflow occurred

hal_status_t HAL_RTC_TIMESTAMP_PollForEvent ( uint32_t timeout_ms )

Poll for timestamp event.

Parameters :

timeout_ms – Timeout duration

Return values :

  • HAL_OK –

  • HAL_TIMEOUT – when the timeout is reached.

hal_status_t HAL_RTC_TIMESTAMP_GetBinaryTime ( uint32_t * p_time_subseconds , hal_rtc_timestamp_information_t * p_info )

Retrieve the RTC timestamp subsecond register value.

Parameters :

  • p_time_subseconds – pointer to a uint32_t to retrieve the value of the subseconds of the timestamp.

  • p_info – pointer to a hal_rtc_timestamp_information_t value. It is used to retrieve the flag of the timestamp event.

Return values :

  • HAL_OK –

  • HAL_ERROR – If an overflow occurred

RTC exported wake-up timer functions

group RTC_Exported_Functions_WakeUp_Timer

Exported wake-up timer functions.

The wake-up timer is a 16-bit auto-reload down-counter. The wake-up timer clock input can be one of:

Call HAL_RTC_WAKEUP_SetConfig and configure hal_rtc_wakeup_config_t::clock to choose the input clock of the wake-up timer. When using the synchronous clock input, the wake-up timer can behave like a 17-bit auto-reload down-counter by setting the value HAL_RTC_WAKEUP_TIMER_CLOCK_BCD_UPDATE_ADD_1BIT to hal_rtc_wakeup_config_t::clock. In this case, the 16-bit down-counter reaches 0 two times; the first time it reloads automatically but triggers a wake-up event. The second time it does not reload automatically but also triggers a wake-up event.

By setting the parameter p_auto_clear_time to a non-zero value in function HAL_RTC_WAKEUP_SetPeriod, the wake-up timer flag is cleared by hardware when the auto-reload down-counter reaches this value.

To configure the wake-up timer without using physical time units, call HAL_RTC_WAKEUP_SetAutoReloadAndAutoClear.

Functions

hal_status_t HAL_RTC_WAKEUP_SetConfig ( const hal_rtc_wakeup_config_t * p_config_wakeup_timer )

Configure the RTC wake-up timer.

Parameters :

p_config_wakeup_timer – Pointer to an RTC wake-up timer configuration instance.

Return values :

  • HAL_OK –

  • HAL_ERROR – If not in initialization mode and wake-up timer is started. If not in initialization mode and WUTWF is still unset after RTC timeout duration.

  • HAL_INVALID_PARAM – When p_config_wakeup_timer is NULL.

void HAL_RTC_WAKEUP_GetConfig ( hal_rtc_wakeup_config_t * p_config_wakeup_timer )

Retrieve the configuration of the RTC wake-up timer.

Parameters :

p_config_wakeup_timer – Pointer to an RTC wake-up timer configuration instance.

hal_status_t HAL_RTC_WAKEUP_SetPeriod ( const hal_rtc_time_t * p_auto_reload_time , const hal_rtc_time_t * p_auto_clear_time )

Program the RTC wake-up timer auto-reload time and auto-reload clear flag time.

Note

hal_rtc_time_t::am_pm field is ignored because it is not used in the SetPeriod function.

Note

hal_rtc_time_t::subsec field is ignored because it is not used in the SetPeriod function.

Parameters :

  • p_auto_reload_time – Pointer to an RTC time instance representing the wake-up reload period.

  • p_auto_clear_time – Pointer to an RTC time instance representing the wake-up auto-clear flag time.

Return values :

  • HAL_OK –

  • HAL_ERROR – The wake-up timer is still in use. The wake-up timer frequency is smaller than 1 Hz; use HAL_RTC_WAKEUP_SetAutoReloadAndAutoClear. Auto-reload time is shorter than auto-reload clear flag time. The value of the auto-reload time is too big or too small or the wake-up timer counter. The wake-up write flag is still cleared after timeout.

  • HAL_INVALID_PARAM – p_period is NULL.

void HAL_RTC_WAKEUP_GetPeriod ( hal_rtc_time_t * p_auto_reload_time , hal_rtc_time_t * p_auto_clear_time )

Retrieve the RTC wake-up timer auto-reload and auto-reload clear value.

Parameters :

  • p_auto_reload_time – pointer to an RTC time instance representing the wake-up reload period.

  • p_auto_clear_time – pointer to an RTC time instance representing the wake-up auto-clear flag time.

hal_status_t HAL_RTC_WAKEUP_Start ( uint32_t interruption )

Start the wake-up timer.

Parameters :

interruption – Specifies the wake-up timer mode.

Return values :

HAL_OK –

hal_status_t HAL_RTC_WAKEUP_Stop ( void )

Stops the wake-up timer.

Return values :

HAL_OK –

hal_status_t HAL_RTC_WAKEUP_PollForEvent ( uint32_t timeout_ms )

Poll for wake-up timer event.

Parameters :

timeout_ms – Timeout duration.

Return values :

  • HAL_OK –

  • HAL_TIMEOUT – If WUTF is unset after timeout duration.

hal_status_t HAL_RTC_WAKEUP_SetAutoReloadAndAutoClear ( uint32_t wakeup_timer_auto_reload , uint32_t wakeup_timer_auto_clear )

Program the RTC wake-up timer auto-reload and auto-reload clear value in binary.

Parameters :

  • wakeup_timer_auto_reload – Wake-up timer auto-reload time in binary

  • wakeup_timer_auto_clear – Wake-up timer auto-reload clear value in binary

Return values :

  • HAL_OK –

  • HAL_ERROR – If WUTF is unset after timeout duration.

uint32_t HAL_RTC_WAKEUP_GetAutoReload ( void )

Retrieve the wake-up timer auto-reload value.

Return values :

uint32_t – Auto-reload value

uint32_t HAL_RTC_WAKEUP_GetAutoClear ( void )

Retrieve wake-up timer auto-reload output clear value.

Return values :

uint32_t – Auto-reload output clear value.

RTC exported IRQ functions

group RTC_Exported_Functions_IRQ

IRQ handler exported functions.

IRQ handler functions to manage the different interrupts:

  • Alarm A and alarm B

  • Timestamps

  • Wake-up timer

  • Subsecond register underflow in binary mode.

Functions

void HAL_RTC_IRQHandler ( void )

Handle RTC interrupt request.

void HAL_RTC_ALARM_IRQHandler ( void )

Handle alarm interrupt request.

void HAL_RTC_TIMESTAMP_IRQHandler ( void )

Handle timestamp request.

Note

Inside the callback, call HAL_RTC_TIMESTAMP_GetDateTime to clear the different timestamp flags (TSF, TSOVF).

void HAL_RTC_WAKEUP_IRQHandler ( void )

Handle wake-up timer interrupt request.

void HAL_RTC_SubSecondsUnderflow_IRQHandler ( void )

Handle subsecond register underflow interrupt request.

RTC exported callback functions

group RTC_Exported_Functions_Callback

Exported callback functions.

Callback functions that can be overwritten for the different interrupts:

  • Alarm A

  • Alarm B

  • Wake-up timer

  • Timestamp

  • Subsecond register underflow only in binary mode.

When rewriting the timestamp callback function, HAL_RTC_TimestampEventCallback, call HAL_RTC_TIMESTAMP_GetDateTime or HAL_RTC_TIMESTAMP_GetBinaryTime to clear the timestamp flags (TSF, TSOVF).

Functions

void HAL_RTC_AlarmAEventCallback ( void )

Alarm A callback.

void HAL_RTC_AlarmBEventCallback ( void )

Alarm B callback.

void HAL_RTC_TimestampEventCallback ( void )

Timestamp callback.

Note

When rewriting this function, call HAL_RTC_TIMESTAMP_GetDateTime or HAL_RTC_TIMESTAMP_GetBinaryTime to clear the different timestamp flags.

void HAL_RTC_WakeUpTimerEventCallback ( void )

Wake-up timer callback.

void HAL_RTC_SubSecondsUnderflowEventCallback ( void )

SSRU callback.

RTC exported attribute management functions

group RTC_Exported_Functions_Attributes

This section provides functions for managing security, privilege and lock configurations.

Functions

hal_status_t HAL_RTC_SetPrivAttr ( uint32_t item , hal_rtc_priv_attr_t priv_attr )

Set RTC item(s) privilege configuration.

Parameters :
Return values :

  • HAL_ERROR – Non-Privileged write to a privilege-only register.

  • HAL_OK – Privilege has been correctly configured.

hal_rtc_priv_attr_t HAL_RTC_GetPrivAttr ( uint32_t item )

Get RTC item privilege configuration.

Parameters :

item – This parameter can be one or a combination of the following values:

Return values :

Returned – value is an element of hal_rtc_priv_attr_t enumeration.